feat(service-automation): a run record says how long it waited (waitMs), so a resumed screen flow no longer reads its user's wait as work - #33511

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-automation, @objectstack/spec, touching 25 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/automation.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/error-handling-client.mdx (via waitMs (symbol, a field of interface ExecutionLogEntry; a field of interface RunRecord))
• content/docs/automation/flows.mdx (via cancelRun (symbol, a top-level function))
• content/docs/kernel/cluster.mdx (via waitMs (symbol, a field of interface ExecutionLogEntry; a field of interface RunRecord))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5be6ef95e0e5d23ae5be87224c5258a58b1b8e9b && git checkout 5be6ef95e0e5d23ae5be87224c5258a58b1b8e9b
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e40cd1e28dd79e60e7f4be0db06f071f3f962574 50c4166cabb364947c6aab50739e07eb4eeefb17 && git checkout -B drift-repro e40cd1e28dd79e60e7f4be0db06f071f3f962574 && git merge --no-ff 50c4166cabb364947c6aab50739e07eb4eeefb17

node scripts/docs-audit/affected-docs.mjs --json e40cd1e28dd79e60e7f4be0db06f071f3f962574

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e40cd1e28dd79e60e7f4be0db06f071f3f962574 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#5 · os-elon-musk · session_016WV4cxHwXNcGcAHNerZsom

Request: review · area A5 · head 50c4166 · 2026-11-14T23:49Z

Contract review: Fixes #32284 under the maintainer ruling A (comment 6879411530). Clause-②: yes (widening) (optional ExecutionLog.waitMs), Metadata-protocol: added. Governed check: NOT governed, 659 lines. CI at request time: 56 success, 10 skipped, Test Core (8/8) still running. os-dev report: comment 6886115077 on #32284. Open question for the reviewer: two nullable number columns on the engine-owned sys_automation_run (active_ms wait clock on a paused or stranded row, wait_ms total on a terminal row), needed so the value survives a resume in a different process. Are they inside ruling A (report recommends keeping both)? Also note the convention choice: a run that never paused carries waitMs: 0, absent means not recorded (mirrors FlowRunSummary.failed / .unmeasured).

Contract-review-claim: session_016WV4cxDxAYxdtDhtR1kQQe · head 50c4166 · 2026-11-14T23:49:49Z

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 50c4166cabb364947c6aab50739e07eb4eeefb17
Local-runs: none
Scope: packages/spec/src/automation/execution.zod.ts + packages/spec/authorable-surface/automation.json, packages/services/service-automation/src/engine.ts, packages/services/service-automation/src/run-resume.ts, packages/services/service-automation/src/dag-traversal.ts, packages/services/service-automation/src/consumed-suspension-restore.ts, packages/services/service-automation/src/run-history.ts, packages/services/service-automation/src/suspended-run-store.ts, packages/services/service-automation/src/sys-automation-run.object.ts

review#2 (server area pilot) · area A5 · Fixes #32284 · maintainer ruling A (6879411530) · published-schema face. CI on this head at review time: 56 success, 10 skipped, 1 in progress, none failing.

① Derived judgments

• Spec. ExecutionLogSchema gains waitMs: z.number().int().min(0).optional(). Its describe matches the semantics the engine writes:

  • durationMs stays the total wall time.
  • waitMs is included in it and summed over every pause.
  • 0 means the run never paused.
  • Absent means not recorded.

  The authorable-surface baseline gains exactly ExecutionLog:waitMs.

• One clock, SuspendedRun.activeMs. It holds the run's executed time at the pause, which is its age minus the wait already accumulated. Every later moment derives the total wait as age - activeMs (waitOfPausedRun), clamped at 0. The clamp exists because startTime may come from another replica's clock. Re-suspending writes the clock forward (activeMsAtPause(durationMs, waitMs)), overriding the ...run spread, so N pauses sum without a list. A suspension with no clock propagates undefined, never a guessed number.

• Every writer of a run record sets the member:

  • Initial execution and each retry attempt (0).
  • First pause (0, plus the clock).
  • Resume, computed once where the claimed pause is consumed and carried to completion, refusal, failure and re-suspend.
  • A paused run that is failed, settled or cancelled where it waits.
  • The operator restore, which keeps the snapshot's clock, so the stranded interval counts as wait.

  A refused resume (lost claim, invalid screen, child still parked) returns before the consume line, so its pause keeps one clock. That matches the comment.

• Durable path.

  • wait_ms is written on the upsert as ?? null, so a rewrite cannot inherit a stale wait, and is read back only when it is a number.
  • active_ms is written on the paused row and on a terminal row's consumed snapshot, and read by both deserialisers via readActiveMs.
  • runRecordToLogEntry carries waitMs, so the served record after a restart or a ring eviction matches the ring.

• Tests cover the cases that matter, and the ablation gives 6 red:

  • never paused gives 0;
  • one pause gives durationMs - waitMs equal to the work;
  • two pauses across two restarts sum;
  • cancel where it waits;
  • restore keeps the clock;
  • no clock leaves the member absent.

② Semver level

• Clause-②: yes (widening) is right: an optional member is added to a published response schema, and nothing is refused.
• Metadata-protocol: added is forced by the authorable-surface baseline moving, the fix(service-automation): a run summary node row carries its steps warnings, so a refused notify channel shows in the trigger response #33438 precedent. Minor on @objectstack/spec and @objectstack/service-automation is the level that line requires. The Skills-docs: none — … line is present and accurate.

③ Boundary flags

• Not security sensitive. waitMs is a duration on a record its caller can already read.
• Two nullable number columns on the engine-owned sys_automation_run. That is platform storage, not authored metadata, so Metadata-protocol is not moved by them. Schema sync adds them. No migration is owed: rows written before this release read waitMs as not recorded, which is the declared meaning of absent, and no legacy-data migration is owed under the current release policy.
• No cross-area file: service-automation and packages/spec/src/automation/** are A5's lease.

④ Design judgment

Rulings on the two questions from the os-dev report (6886115077):

• Q1: both columns are inside ruling A; keep them. Ruling A puts waitMs on the published run record. The card's own case is a screen flow resumed by a different process than the one that paused it, and it is answered from the durable row.
  • Without active_ms the resuming process cannot know when the pause began, so the value would be absent exactly where the card needs it.
  • Without wait_ms a run read back after a restart or a ring eviction would lose it.
  • Both columns are the storage of the ruled member. They add no second member and no second meaning, and durationMs is untouched.
  • The single-clock design (activeMs, not a list of pause instants) is the minimal state that sums any number of pauses across restarts and replicas.
• Q2: keep 0 = measured, absent = not recorded. It matches FlowRunSummary.failed/.unmeasured in the same file, and it keeps a pre-release paused run from reading as "never waited". The spec describe and the jsdoc both say "absent is not zero".

Nits (none blocking):

• N1: a paused entry's waitMs is frozen at the moment it was written, so a run paused for hours on its first pause reads waitMs: 0 in the list until it resumes. The describe says so ("the wait up to the moment the entry was written"). Noted only so nobody files it as a bug.
• N2: the restore path counts the failed resume attempt's own execution time as wait. The comment says so, and the step log ends at the pause, so the derived "executing" figure matches what the record shows. This is the right call; it is noted only for the docs page.

Implemented-by: claude/area-A5-32284
Reviewed-by: session_016WV4cxDxAYxdtDhtR1kQQe

VERDICT: PASS

Nits only, so this is the final round. Land once the last check is green.

domain:server#5 · os-elon-musk · session_016WV4cxHwXNcGcAHNerZsom

ACCEPT · area A5 · head 50c4166 · 2026-11-14T23:51Z

• Cards: Fixes automation run record: a resumed run's durationMs counts the time it waited for the user, so a screen flow reads as 18.7 s of work #32284 (maintainer ruling A, comment 6879411530).
• Review: review#2 contract review PASS at this head (comment 6886157000). Clause-②: yes (widening) and Metadata-protocol: added ruled right; Q1 the two nullable sys_automation_run columns (active_ms, wait_ms) are the storage of the ruled member and stay; Q2 0 = measured, absent = not recorded. Nits N1/N2 are documentation notes only (no card).
• Governed: check-governed-merges.mjs --pr 33511 → NOT governed, 659 changed lines.
• Checks: all green on this head; mergeable_state clean.
• Landing: ready + auto-merge under the maintainer's standing area rule (15:21Z, A5 thread).